Create Hosted Essentials Service

The Create Hosted Essentials Service request creates a new Hosted Essentials Service with a single SIP Connection with the Hosted Essentials license type.

URL

Copy

{{baseUrl}}/api/v2/customer

HTTP Method

POST

Request Body

Parameter

Type

Description

shortName

string

Short customer name, complying with validation rules for customer name:

■

The string should be 3-15 characters long

■

The following characters cannot be used: \ / : * ? " < > |audit

■

Can contain letters (lower/UPPER case), Numbers and special characters are allowed, however cannot contain the dot (.) or blank spaces.

■

Unique name per M365 Tenant

fullName

string

The customer full name (optional).

siteLocation

list array

The site location represents an SBC configuration for a specific customer. This list array includes the following parameters:

■

sbcid

■

sbcOnboardingScript

■

sbcCleanupScript

sbcId

integer

The SBC Id in the SBC List (Known SBCs). For more information, see Managing SBC Devices.

sbcOnboardingScript

integer

The required value for an SBC Onboarding script. For more information, see SBC Template Scenarios.

sbcCleanupScript

integer

The required value for an SBC Cleanup script (see SBC Template Scenarios).

ovocCustomerType

string

One of the following values:

■

IPGROUP_TYPE

■

TENANT_TYPE

■

IPGROUP_TYPE: An IP Group is created for each new customer based on the Customer Shortname. This type is used for the Access Trunk Direct Routing (used for Direct Routing customers when SIP Registration is required). An link is established with the Live Platform server (OVOC) using this IP group.

■

Tenant ID:-The new customer is created based on the customer's Azure tenant subscription Id. A link is established with the Live Cloud server (OVOC) using this tenant Id.

msTenantId

string

Microsoft Tenant ID of customer tenant for validation.

channelId

string

The channel Id of the customer tenant. See Get List of Channels.

lcCustomerId

string

The Id of the Customer entity in the Operation Center portal. When you specify this value, the new service is created under this entity in the Live Platform topology tree.

This value is currently not retrievable using the REST API. If not specified, both a new customer and service entity are created as separate entities in the Operation Center portal with the same shortName as shown in the example figures below.

Workaround: As a temporary workaround for retrieving this value:

Select the relevant customer entity in the Operation Center portal.

Open the F12 Debugging mode, select the tabs as shown in the figure below.

Copy the 'id' value for the relevant customer.

SbcConfigurationType

integer

One of the following values:

■

SIP Trunk

■

BYOC

■

IPPBX

This value is currently not supported.

Script parameters

list array

The following Script parameters can be sent in this request:

■

CacProfile

■

ProxySet

■

OnlinePstnGateway

■

CarrierUserName

■

CarrierUserPassword

■

CarrierMailLine

■

CarrierHostName

■

CustomVar.Variable<VariableSequenceNumber>

CACProfile

string

The preconfigured value for Number of CAC sessions" e.g. "10 sessions" (see Get SBC Devices)

Proxy Set

string

The SBC Proxy Set value e.g. SIP Trunk

OnlinePstnGateway

string

The Online PSTN Gateway for the SBC device managing calling functionality for the tenant.

CarrierUserName

string

The digest MD5 Authentication username. The valid value is a string of up to 60 characters. By default, no value is defined.

CarrierUserPassword

string

The digest MD5 Authentication password. The valid value is a string of up to 50 characters. Note: The password cannot be configured with wide characters.

CarrierMainLine

string

The AOR username. This appears in REGISTER From/To headers as ContactUser@HostName.

CarrierHostName

string

The Address of Record (AOR) host name. The host name appears in SIP REGISTER From/To headers as ContactUser@HostName.

CustomVar.Variable<VariableSequenceNumber>

string

where <VariableSequenceNumber> is the sequence in database that the variable is defined in the 'Customer variables' column for the script properties (see Customer Variables).

For example, when the following IP-PBX variables are defined in the database in the order: IPPBX-ProxyAddress, IPPBX-ProxyAddress-SIPPort, SIP-HostName then Custom variables should be defined as follows:

■

CustomVar.Variable1: <: IPPBX-ProxyAddress>

■

CustomVar.Variable2: < IPPBX-ProxyAddress-SIPPort>

■

CustomVar.Variable3: <SIP-HostName>

Custom variables can be defined to update specific parameters on the SBC device. These variables must be predefined in the UMP-365 database (see Customer Variables). Also verify that the custom variables notation has been added to the script (see parameter 'sbcOnboardingScript' above) that you are applying to the request.

There is no limitation for the number of variables that are added.

additionalProp1

string

One of the following values:

■

SBC name (Provider SIP Trunk, BYOC or IP-PBX)

■

Region name

■

Carrier name

additionalProp2

string

One of the following values:

■

SBC name (Provider SIP Trunk, BYOC or IP-PBX)

■

Region name

■

Carrier name

additionalProp3

string

One of the following values:

■

SBC name (Provider SIP Trunk, BYOC or IP-PBX)

■

Region name

■

Carrier name

Example Body

Copy

{
  "shortName": "SaraTest1",
  "fullName": "SaraTest1",
  "siteLocation": {
    "sbcId": 5,
    "sbcOnboardingScript": 10007,
    "sbcCleanupScript": 10700
    },
  "ovocCustomerType": "IPGROUP_TYPE",
  "msTenantId": "4bf50a33-a383-4d3f-9403-220c898bc1b2",
   "scriptParameters": {
    "CacProfile": "5 sessions",
    "ProxySet": "SIPTrunk",
    "OnlinePstnGateway": "BradDRService.sandbox2.audiocodes.be",
    "additionalProp1": "Service Provider2 SBC"
}
 
  }

Example Response

Copy

{
    "id": "b38e5a04-6d32-4be8-95bb-53bf7d6fa95c",
    "customerId": "SaraTest1",
    "siteLocationIds": [
        "2205294f-9111-4e9d-8343-bd24f8e7a90f"
    ],
    "deploymentState": "Deployed",
    "errorDetails": null,
    "progressDetails": "(Information, MsTenantid is valid);(Information, Customer data created!);(Information, SBC sbc-onboarding done for site SaraTest1.);(Information, CreateSiteInOvoc started.);(Information, Site created in Ovoc)"
}

In the Body shown above, the 'lcCustomerId' value is not specified, therefore separate entities are created in the Operation Center portal for both the customer and service entities, as shown in the figures below.

In the example below 'lcCustomerId' is included in the Request Body.

Example Body (including 'lcCustomerId')

Copy

{
  "shortName": "BradTest3",
  "fullName": "BradTest3",
  "siteLocation": {
    "sbcId": 5,
    "sbcOnboardingScript": 10007,
    "sbcCleanupScript": 10700    
    },
  "lcCustomerId": 1317027,
  "ovocCustomerType": "IPGROUP_TYPE",
  "msTenantId": "4bf50a33-a383-4d3f-9403-220c898bc1b2",
   "scriptParameters": {
    "CacProfile": "5 sessions",
    "ProxySet": "SIPTrunk",
    "OnlinePstnGateway": "sandbox1.audiocodes.be",
    "additionalProp1": "Service Provider2 SBC"
}
 
  }

Example Response

Copy

{
  "shortName": "BradTest3",
  "fullName": "BradTest3",
  "siteLocation": {
    "sbcId": 5,
    "sbcOnboardingScript": 10007,
    "sbcCleanupScript": 10700    
    },
  "lcCustomerId": 1317027,
  "ovocCustomerType": "IPGROUP_TYPE",
  "msTenantId": "4bf50a33-a383-4d3f-9403-220c898bc1b2",
   "scriptParameters": {
    "CacProfile": "5 sessions",
    "ProxySet": "SIPTrunk",
    "OnlinePstnGateway": "sandbox1.audiocodes.be",
    "additionalProp1": "Service Provider2 SBC"
}
 
  }

As a result of including the 'lcCustomerId' parameter in the Request Body, the new service is created under the customer name corresponding to the specified 'lcCustomerId value.

HTTP Responses

■

200 OK

Parameter

Type

Description

string

Unique customer Id created by this request (customerGuid).

customerId

string

ShortName of the Customer service.

siteLocationIds

integer

■

For deployments with a single location, this value is identical to the 'customerGuid' value above.

■

For deployments with multiple locations, this value is unique.

deploymentState

string

One of the following values:

■

Unknown

■

Deployed

errorDetails

string

Error information.

progressDetails

string

Progress details regarding the deployment. See example below.

Copy

Checking SBC IP Group Programming.SBC not programmed yet.Starting SBC Programming.Sbc is programmedSite location information saved.Customer created